Macwelt 1/Macwelt DVD 1.toast/Web-Publishing/HTML-Editoren/Alpha ƒ/Help/Alpha Manual

Text File | 2001-02-08 | 114.4 KB | 2,849 lines

The Alpha Manual

                                               version: 7.4.1
                                               created: 00-12-07 17.58.19
                                           last update: 01-02-08 21.03.33

    Copyright © 1990-2001 Pete Keleher. All Rights Reserved

The Tcl code is copyright its respective authors

    Please note:

The manual is always being updated, and is about 90% finished.  Other parts
of the documentation still need a major overhaul.

    Legal notice

The Author(s) of this product are in no way liable for any direct or
indirect damage caused by the product.

You may freely copy and distribute Alpha, but please bear in mind that
Alpha is Shareware.  If you decide to keep it, please <<register>> your
copy by selecting 'Register' from the 'About…' dialog.


          Introduction


Alpha is a very powerful, multi-purpose text editor.

Alpha is multi-modal, which means it switches between different modes
depending on which type of document you are editing.  Everybody who has
used Emacs knows about this concept.  The idea with different modes is to
change Alpha's behavior depending on which kind of text you're editing.
For example if you're programming in C++ or editing a LaTeX document you
want different features.

Alpha is very customizable.  Much of Alpha's functionality is implemented
in 'packages' or 'extensions'.  The "Config --> Preferences --> Features"
and "Config --> Mode Prefs --> Features" menu items let you see which items
are installed, and lets you turn them on and off.

Alpha uses Dr.  Ousterhout's Tool Command Language (Tcl) as an extension
language.  Many of the functions bound to keystrokes, as well as many of
the functions in the menus, are written in Tcl.  All the "Packages" or
"extensions" just mentioned are all written in Tcl.  Anybody who wants can
write new packages for Alpha!

Of course, you don't have to learn Tcl to use Alpha.  You can have lots of
use of Alpha without knowing anything about Tcl.  But if you want to become
a real power user, you should consider trying it out.  Then the
possibilities of customizing Alpha are unlimited.

Alpha contains source from many places, but in particular I'm grateful to
Ray Johnson and Tim Endres for their working on porting TCL to the mac, and
to Tom Scavo and Tom Pollard for their Tcl code contributions.  The
following people have also provided considerable code and/or help debugging
the one or two bugs Alpha has had: Masatsugu Nagata, Karl J. Smith, Eric
Sink, David C. Black, Richard T. Austin, Henry Spencer, Vince Darley, Johan
Linde, Tom Fetherston, Jon Guyer and Jerry Fowler.


               How to navigate the documentation?


This manual is divided into four major sections.  The first deals with
Alpha's standard menu items, basic editing, and "international" issues.
The second addresses more Alpha specific behavior, such as file marking,
window management, and command (double) clicking.

The third section introduces "Modes" and "Packages", contained in the
AlphaTcl library.  These are the items that sets Alpha apart from most text
editors available -- many of these features are addressed in greater detail
in other Help Menu items as well.  The final section contains information
on changing or extending Alpha's behavior.

You can quickly jump between different sections of the manual by using the
menu you find under the M icon at the right top of this window.  Also,
Alpha supports a limited form of hypertext.  Clicking on green underlined
text executes a command associated with the underlined text, usually taking
you to other documentation, like this --> (jump to "Quick Start".)
Control-<period> will bring you back.


    ======================================================================


          Alpha's Menus


This section is an explanation of Alpha's main menus, from "File" to
"Windows" (menu with the window icons).  The menu items listed here are the
ones available when no features are enabled in the (using the menu item
"Config --> Preferences --> Features…").  Some of these features add new
menu items or new submenus to Alpha's main menus.

Alpha uses Ramon Felciano's Mercury MDEF to display menus. In addition to
allowing other modifiers to be shown in the menu, this MDEF also allows
alternates, items that change depending on the state of the modifier keys.
Alternate items are tagged below by the modifier that must be pressed to
display it.

               File


  New                           New file.
  Open…                         Open file.
  Close                         Close file.
  Close All (option)            Close all files.
  Close Float (shift)           Close a palette.

  Save                          Save file.
  Save All (option)             Save all files.
  Save Unmodified (control)     Save file without changing the modification
                                date.
  SaveAs…                       Prompt for name to same file under.
  Save A Copy As… (option)      Save a copy of the open window.
  Rename To… (shift)            Rename file.

  Revert                        Revert to last saved version,
                                  throw away undo history.
  Revert To Backup (option)     Revert to last backup copy, if any.

  File Utils

    File Remove…                Remove a file.
    File Info…                  Display/edit info about a file.
    Text to Alpha               Set creator of text files in a folder to Alpha.
    Show in Finder              Select the front window in the Finder.

  Page Setup…                   Set print options.
  Print…                        Print window.
  Print All (option)            Print all windows.

  Quit                            Quit Alpha.


               Edit


  Undo                          Undo.
  Redo                          Redo.

  Cut                           Cut selection to scrap.
  Copy                          Copy selection to scrap.
  Paste                         Paste from scrap.
  Select All                    Select entire file.
  Select Paragraph (option)     Select current paragraph.
  Clear                         Delete selection.

  Twiddle                       Exchange characters bracketing the
                                  selection point.
  Twiddle Words (option)        Exchange words bracketing the selection point.

  Shift Left                    Shift selection left one tab.
  Shift Left Space (option)     Shift selection left one space.
  Shift Right                   Shift selection right one tab.
  Shift Right Space (option)    Shift selection right one space.
  Balance                       Select text out to the next set of
                                  matching braces.


               Text


  Fill Paragraph                "Fill" paragraph that contains the
                                  insertion point.
  Wrap Paragraph (option)       Break lines longer than 'fillColumn' in
                                  paragraph containing the insertion point.
  Sentence Paragraph (option-shift) - Forces each sentence to start on new
                                       line.
  Fill Region                   "Fill" selection subject to 'leftFillColumn'
                                  and 'fillColumn'.
  Wrap Region (option)          Break lines longer than 'fillColumn' in selection.
  Sentence Region (option-shift) - Forces each sentence to start on new line.

  Line To Paragraph             Convert a line to a paragraph.
  Paragraph to Line (option)    Convert a paragraph to single line.

  Sort Lines                    Sort selected lines.
  Reverse Sort (option)         Sort selected lines backwards.
  Spellcheck Window             See the section below on "Spell Checking".
  Spellcheck Selection (control)

  Zap Invisibles                 Delete all chars in file with ASCII code
                                  < 32, except for LF, TAB and CR.
  Tabs To Spaces                Convert tabs to space runs.
  Spaces To Tabs (option)       Convert space runs to tabs.

  Indent Line                   Indent the current line.
  Indent Selection (option)     Indent the selection.

  Upcase Region                 Upcase all chars in region.
  Downcase Region (option)      Downcase all chars in region.

  Strings

    Insert Prefix               Prepend string 'prefixString' to every line in
                                  selection.
    Remove Prefix (option)      Remove prefix string from lines in selection.
    Insert Suffix               Append string 'suffixString' to every line in
                                  selection.
    Remove Suffix (option)      Remove suffix string from lines in selection.
    Set Prefix                  Change prefix string.
    Set Suffix                  Change suffix string.

  Comment Line                  Comment out line, considering mode.
  Uncomment Line (option)       Un-comment line, considering mode.
  Comment Box                   Create a comment box around selected text.
  Uncomment Box (option)        Remove such a comment box.
  Comment Paragraph             Comment out a paragraph.
  Uncomment Paragraph           Uncomment a paragraph.


               Search


  Find…                         Present a search dialog.
  Search Start (option)         Return selection point to where the last search
                                  started.
  Find Again                    Search forward again with same settings.
  Find Again Backward (option)  Search backward again with same settings.
  Find in Next File             Restart multiple-file search in next file after
                                  stopping at a match.
  Enter Search String           Use the current selection as the search text.
  Enter Replace String (option) Use the current selection as replace text.

  Quick Find                    Incremental search forward (grep, match words
                                  off, ignore case on). Type chars to define
                                  string, control-w adds the current word to
                                  the search string, control-s/r search for
                                  the same string again.
  Quick Find Regexp (option)    Same as Quick Find but lets you use a regular
                                  expression.
  Reverse Quick Find            Same thing in reverse.

  Replace                       Replace the selection.
  Replace and Find Again        Replace the selection and search again forward.
  Replace All                   Replace all of occurrences of the search string
                                  in the rest of the file.
  Replace in Fileset (control)  Global replace in fileset.

  Place Bookmark                Set a book mark at the current position,
                                  pushing it onto a "stack".
  Return to Bookmark            Pop last bookmark from stack and go to it.
  Goto Line                     Go to specific line number.

  Matching Lines                Find all lines that match a regular expression
                                  and summarize in new window.
  Goto Match                    Jump to the original text specified by the
                                  current line in a "Batch Find" or
                                  "Matching Lines" window.
  Next Match                    Jump to the original text specified by the
                                  next line in a "Batch Find" or
                                  "Matching Lines" window.
  Goto Func                     The same as selection an item in the Funcs menu
                                  (the one with two curly braces at the right
                                  top of the window)
  Goto File Mark                The same as selection an item in the Marks menu
                                  (the one with the M icon at the right top
                                  of the window)
  Mark Hilite                   Select text last manipulated, such as from
                                   a paste.

  Named Marks->                 Manipulating named marks.

  Unnamed Marks

    Set…
    Exchange Point And Mark


               Utils


  Compare

    Windows                     Compare top two windows, sending output to
                                  a third.  Selecting a line in the third
                                  window and hitting return (or enter) moves
                                  that line to the top of the window.
    Files                       Same as above, but prompts for files.
    Directories                 As above, but works for entire folders.

  Win Utils

    Insert Path Name…           Prompt for a file and insert complete pathname
                                in window.
    Insert File…                Insert the text of another file.

  Ascii Etc

    Quote Char                  Wait for key press and insert key.
    Key Code                    Wait for key press and insert keycode
                                  and modifier string suitable for key binding.
    Key Ascii                   Same as above, but use ascii form.
    Get Ascii                   Display ascii code for char to right of
                                  insertion point.
   Insert Ascii                 Prompt for ascii code and insert character.

  Shell                         Start up command-line shell that interprets Tcl
                                  commands. The shell has a few csh-type
                                  features, such as 'ls', 'rm', etc. commands,
                                  as well as file completion with the TAB key.
  Toolserver Shell (control)    See the "Shells" help file.
  Calculator (shift)            See the "Calculator Help" file.

  Word Count                    Count lines, words, chars in window.
  Send URL                      Send selection as URL to proper internet
                                  application.
  Cmd-Double Click              See the section below on
                                  'Command-double-clicking".

               Config


  Preferences                   Set global preferences.

    Menus…                      Change global menus.
    Features…                   Change global features.
    Suffix Mappings…            Displays and allows editing of suffixes (really
                                  filename patterns) for all existing modes.
    Save Preferences Now        Save any preferences set during this session.
    Edit Prefs File             Put your own arbitrary startup code here.
                                Loaded after all standard Tcl code.

    Interface Preferences etc.  The rest of this menu is used to set preferences.

  Packages

    Miscellaneous Packages…     Set preferences for packages.
    Describe A Package…         Show a description of a package.
    Read Help For A Package…    Opens the documentation for a package.
    Uninstall Some Packages…    Uninstall one or more packages.
    Internet Updates->          To download packages from Internet.
    Rebuild Package Indices     The Alpha's index of all installed
                                  packages.

  Mode Prefs                    Set preferences for current mode.

    Menus and Features…         Change current mode's menus and features.
    Preferences…                Change options for current mode.
    Edit Prefs File             Edit mode-specific preferences.  Loaded
                                  after mode entered for the first time.
    Load Prefs File               Load current mode's preferences.
    Describe mode               Describe current mode's variable settings and
                                  bindings.
    Change Mode…                Change the current mode.

  Set Font Tabs…                Change font and/or tabs for current file.
  Special Keys…                 Set key bindings for electric features.
  Describe Binding…             Wait for a keystroke, then display that
                                  keystroke's binding.
  List Packages                 Create the "Packages" help file.
  List All Bindings             List all current key bindings.
  List Global Bindings (option) List all current global key bindings.
  List Functions                List all functions currently defined, both
                                  "core" functions (those coded in C), and
                                  those coded in the supplied Tcl files.
  View Saved Settings…          Any variables or flags that you modify during
                                  the course of a session are saved to files
                                  in the system preferences folder when
                                  Alpha quits. This function shows all
                                  such saved variables.
  Remove Saved Settings…        This function allows settings to be removed.

  Redefine Colors->             See the section below on "Coloring".


               Windows (an icon with three windows)


  Zoom                          Zoom windows in and out.
  Default Size (option)         Resize window to default size.
  Choose A Window               Choose window to select from list (proc
                                  chooseAWindow).
  Iconify                       Toggle iconification of front window.
  Arrange->                     Rearrange open windows.

  Split Window                  Split window into two panes, or unsplit.
  Toggle Scrollbar              Toggle the horizontal scrollbar on the
                                  frontmost window.

    ----------------------------------------------------------------------


          Basic editing


The very basics for editing text with Alpha is the same as in any other
Mac application, but Alpha has a number of key shortcuts to speed up your
work, and a couple of features not found in similar applications.
Emacs user will also be happy to know that many of the basic keybindings
used in Emacs are supported by Alpha. However, this requires that you
switch on the Emacs package. Read more in the file "Emacs Help".


The following is a list of some of the most commonly used key bindings in
Alpha's default setup, those that are generally not listed in any menus:


               Help

'help'                                    open the "Alpha Manual" help file

control-'help'                            open any available help for the mode
                                          of the frontmost window.

               Moving the Cursor


left-arrow           or  control-b      backward character
right-arrow          or  control-f      forward character

command-left-arrow   or  control-a      beginning of line
command-right-arrow  or  control-e      end of line

option-left-arrow    or  option-b       backward one word
option-right-arrow   or  option-f       forward one word


up-arrow             or  control-p      previous-line
down-arrow           or  control-n      next-line

command-up-arrow     or  'home'         beginning of window
command-down-arrow   or  'end'          end of window

option-up-arrow      or  'Page up'      move one page backward
option-down-arrow    or  'Page down'    move one page forward

control-up-arrow                        scroll window up one line
control-down-arrow                      scroll window down one line



               Selecting Text


shift-left-arrow                extend selection one char left
shift-right-arrow               extend selection one char right

shift-up-arrow                  extend selection one line up
shift-down-arrow                extend selection one line down

shift-option-left-arrow         extend selection one word left
shift-option-right-arrow        extend selection one word right

control-h                       select next word

shift-command-left-arrow        select to beginning of line
shift-command-right-arrow       select to end of line


command-B                       select smallest set of parentheses, braces, or
(Balance in Text menu)          brackets that encloses the current selection

double-clicking                 select a word
triple-clicking                 select a line


Control-double-clicking on any type of parentheses or bracket selects from
the parentheses or bracket to its mate. Without the control key held down,
only the intervening text is selected.


               Deleting Text


'del'      or  control-d        delete forward char
'delete'                        delete backward char
option-d                        delete forward word
option-h   or  option-delete    delete backward word
control-k                       delete to end of line


               Twiddle, Shifting Text


The following functions are found in the Text menu.

Twiddle (command-`)                  Exchange characters bracketing
                                     the selection point.
Twiddle Words (command-option-`)     Exchange words bracketing the
                                     selection point.

Shift Left (command-[)               Shift selection left one tab.
Shift Left Space (command-option-[)  Shift selection left one space.
Shift Right (command-])              Shift selection right one tab.
Shift Right Space (command-option-]) Shift selection right one space.


               The Numeric Key Pad


Alpha starts up with the Num Lock off so that the numeric key pad can be
used as a navigation tool.

0   Scroll back one page
1   Jump to the start of the nearest function above the current position *
2   No special function; types a "2"
3   Jump to the start of the nearest function below the current position *
4   Move to beginning of current word
5   Marks current insertion point and moves cursor to previous mark.

    Note: This is extremely useful for navigating across text chunks.  Try
    'paste'-ing a large chunk of text, and then immediately hit Keypad 5.

    Try 'put cursor at top/bottom of document' (Keypad 0 or .), and then
    immediately hit Keypad 5.  After a few minutes, you won't be able to
    live without Keypad 5...

6   Move to end of current word
7   Delete all characters from current insertion point to beginning of word
8   Put cursor at top of document (new in 7.4.x)
9   Delete all characters from current insertion point to end of word

.   Put cursor at bottom of document
+   Cycles between the two topmost windows
-   Makes the previous window topmost

shift-clear   Turns num lock off, allowing you to use the keypad for numbers
clear         Move the current line to the top of the window
enter         Page forward

* Note: in modes where no function specifying pattern exist, 1 and 3 just
look for parenthesis (e.g. text mode).  Also, in Tcl trace dumps these keys
help follow Tcl calls and returned values (advanced stuff)

The =, /, * keys function normally.

To turn off these special navigation functions, turn on the Num Lock (using
shift-clear).

Turning the Num Lock off will recover the navigation features of the
numeric key pad.


               Drag and Drop editing


Alpha supports drag and drop cut, copy, clear, and paste.  To use this
feature, select some text, then move the cursor over the selected text.
The cursor should then turn into an open hand.  Mouse down, and move the
cursor to the place you wish to paste the text.  When the mouse is
released, the hilighted text is moved to the new location.

Option-mouse does a "copy" instead.  You can also drag selections between
windows and to and from other applications, including the Finder.  Text
dragged to the Finder is saved in a text clip file.  Text can be deleted by
dragging it to the trash can.

You can also drag any text file to an Alpha window to insert the content of
the file in the window.

You MUST have system 7.5 or above or Apple's "Macintosh Drag And Drop"
extension installed.  Get a copy from Apple or via Alpha's web page.


               Rectangular Editing


If the option key is pressed while the mouse is dragged, a rectangular
section of text is selected instead of the normal selection.  This
rectangular selection may extend over multiple lines, but contains only
text between the column of the drag start and the column of the drag end.
The drag cannot end on a column or row less than the start.  This selection
can be extended by option-shift-mouse, but not dragged further.

The rectangular selection can be deleted, copied, and pasted.  This is very
useful for tables and arrays, such as in LaTeX. Usually, the operation will
be intuitive.  However, if you use proportional fonts the selection may
appear ragged.  If some of the line contain tabs, the result may not be
want you want.  Converting tabs to spaces in the desired region before
attempting rectangular selection usually fixes the problems.


               Fill Routines


The 'fill' and 'wrap' routines reformat text to specified line lengths.
This is useful in two case.  First, word processors such as Microsoft Word
only insert carriage returns at the end of paragraphs.  Secondly, while
typing and inserting text into pre-existing paragraphs, the line lengths
become unequal.

The 'wrap' routine handles word processor documents quickly by merely
inserting carriage returns as necessary to ensure all lines in the selected
region are shorter than specified by the preference 'Fill Column'.  Alpha
asks the user if wrapping should be done whenever the user opens files that
have lines longer than 'Para Column' characters.  This feature can be
defeated by including the word 'nowrap' anywhere on the first line.

The 'fill' routine goes further.  Not only does it break lines, but it also
coalesces lines to eliminate short lines.  The routine works by stripping
the relevant text of white space, then re-inserting white space and
carriage returns so that no line extends past 'Fill Column' characters in
length and begins with 'Left Fill Column' spaces characters.

The preferences 'Fill Column', 'Para Column', and 'Left Fill Column' can
all be set in the dialog "Config --> Preferences --> Text".

Both the fill and wrap routines come in two flavors, 'Fill/Wrap Paragraph'
and 'Fill/Wrap Region'.


               Fill Paragraph


If there's a selection, then Alpha fills all paragraphs in that selection.
If not then Alpha fills the paragraph surrounding the insertion point.  The
definition of a 'paragraph' may be mode dependent, but in Text mode it is
the text between the closest empty lines.  Fill Paragraph also uses an
extra preference 'Double Spaces', which determines if an extra space after
should be placed after the '.'  at the end of each sentence.  This
preference is set in the dialog "Config --> Preferences --> Text".


               Fill Region


If there's a selection, then Alpha fills all paragraphs in that selection.
If not then Alpha fills the region between the insertion point and the
mark.


               Wrap Paragraph


Wrap the paragraph surrounding the insertion point.


               Wrap Region


If there's a selection, then wrap the selection.  If not then wrap the
region between the insertion point and the mark.


          Key bindings


Many of Alpha's menu items are bound to specific keys.  In general, key
binding information is given to the right of any menu command.

Alpha includes many key bindings that go beyond those found in most
software applications.  Many of them are bound to specific menu items, and
are displayed next to the item's name.  Modifier keys (for the Macintosh)
include "command", "option", "control", and "shift".  As of this writing
the option key is not available for AlphaTk, although "escape" can serve as
a meta-key.

To quickly find out what a specific key is bound to, use the menu item
"Config --> Describe Binding", and then press the key combination in
question.  If you look closer at the "Config" menu, you'll also see that F7
is bound to this menu item.  For example, type

    F7
    <command>-S

and you'll see that command-S is bound to

    menu::fileProc "File" "save"

(command is the "Apple" key on the Macintosh, by the way, and "alt" on a PC)

Sometimes the information given by F7 will seem somewhat cryptic, because
these are the actual Tcl commands, but in general it is easy to decipher
what is going on.

If you take a look at the "File" menu, you'll see that "Save" also gives
the key binding information -- if you find yourself using the same menu
commands over and over again, learning a few of these bindings can save a
lot of time and travel of the mouse.

The "Config --> List All Bindings" menu item will list all current key
bindings, or you could just click here --> <<global::listAllBindings>>.

Alpha allows you to customize the keystrokes you use to invoke editor
functions.  Any Tcl command (or accented characters) can be bound to any
single keystroke.  See "Default Key Bindings" for more information.


    ----------------------------------------------------------------------


          International Users


There is a basic problem international users will notice, which have to do
with the fact that the keyboard layouts are different in different countries.
Therefore some keybindings in Alpha may not work with all keyboards. For
example, on a Swiss keyboard, '/' is shift-7 (which means you have to press
shift to get '/'. This means there is no difference between cmd-/ and
shift-cmd-/ on such a keyboard. In Alpha these are bound separately to
'zoom' and 'singlePage'.

If you're using a western keyboard Alpha can solve some of these problem
for you.

First: Activate the "International Menus" feature. It replaces some
keybindings in the menus and solves problems like the one just described.
However, only key bindings in the global menus "File" to "Windows" are
modified. Any other menu may still have problems.

Second: Tell Alpha which keyboard layout you're using in the preferences
dialog "Config --> Preferences --> International".  (In a future version,
Alpha should be able to get this information from the OS directly.)  This
will make sure that some bindings not defined in the menus work, e.g. that
the electric braces work.  However, problematic bindings defined in the
various packages are usually not cured by this.


               Which menu items are affected?


The menu items that the International Menus package change are (depending
on which keyboard layout you use, some of these may remain unchanged):

Edit menu: Twiddle, Twiddle Words, Shift Left/Right, Shift Left/Right Space
Search menu: Return to Bookmark, Goto Line, Mark Hilite
Windows menu: Zoom, Default Size, Choose A Window


               Teaching Alpha new keyboard layouts


If you're not using a western keyboard or if you do encounter any problems,
reading the following section will help to clarify things and should help
you to fix the problem. This section requires that you first read the
section Changing Alpha's behavior. If you need help defining
a new keyboard layout, subscribe to the ALPHA-D mailing list and ask for help.

To solve the problem with bindings in the menus you can use the
command: menu::replaceWith. To solve the problem with the Swiss keyboard
described above you would add the following to your preferences file:

    menu::replaceWith winMenu [list "//<Szoom" "//<S<I<OsinglePage"] \
        items "<S//zoom" "<S<O<U/=singlePage"

To define your keyboard layout, add a line like this to your preferences
file:

    set "keyboards(U.S.)" {
     {§1234567890-=[];'\`,./}
     {±!@#$%^&*()_+{}:"|~<>?}
     <U/[
     <U/]
    }

The first two lines tell Alpha how to map using the 'shift' key. Shift maps
each item in the upper string into the corresponding item in the lower
string.

The third and forth lines defines the keybindings for the left and right
braces, in this example to shift-[ and shift-].

See the file "alphaDefinitions.tcl" for examples of keyboard layout
definitions.

If you define an array entry keyboards(my-country), then you can just
select that in the international prefs dialog, and Alpha will set the flags
correctly. You can then send that keyboard array entry to the ALPHA-D
mailing list for inclusion in a future version of Alpha.

If a package wishes to be told when the keyboard changes, it can do
that by registering with the 'removekeyboard' or 'keyboard' hooks like
this:

    # tell me when we switch to a "Swiss German" keyboard
    hook::register keyboard keys::swiss "Swiss German"
    # tell me when we disable a keyboard
    hook::register removekeyboard my_disable_proc
    # tell me when we enable a keyboard
    hook::register keyboard my_enable_proc

In this way a clever package could remove the need for restarting
Alpha by unbinding and then rebinding all necessary items.


    ----------------------------------------------------------------------


          Undo + Redo


Alpha supports unlimited undo and redo.  This means that most changes can
be undone, and then redone, at will.  Bear in mind that once you create new
modifications, all changes that you have undone but not redone are lost.
Another point to bear in mind is that saving a buffer to disk flushes the
undo buffer.


          Text Wrapping


Alpha can wrap the text as you type in three different ways.  How Alpha
wraps the text can be set for each mode.  Presumably you want Alpha to wrap
plain text files, like this one, but not to wrap programming code.  How the
wrapping is done is indicated in the leftmost popup menu in the statusbar,
where also the way of wrapping can be changed.  A change affects the
current mode, not only the current window.  The three ways of wrapping are:

    None

No wrapping.

    Wrap

When you type beyond 'Fill Column' positions, Alpha inserts a line break to
make you continue typing on the next line.

    Soft

Soft text wrapping is re-formatting the rest of the paragraph on-the-fly as
text is inserted and deleted.  Soft-wrapping is enabled by selecting "Soft"
in the wrap popup menu in the status bar.  The text to be wrapped is
delimited by the current line and the last line in the current paragraph.
Wrapping occurs after insertions that result in the current line becoming
longer than 'Wrap High' characters long (tabs counted as one character), or
deletions where the length of the line (tabs likewise) becomes less than
'Wrap Low' characters long.

The soft wrapping is not "true" soft wrapping like the one used by word
processors.  Alpha rather reformats the paragraph and inserts line breaks
at new positions on-the-fly.

The values for 'Fill Column', 'Wrap High', and 'Wrap Low' can be changed in
the dialog "Config --> Preferences --> Text".


          Indentation


Alpha automatically indents the text for you to make it easier to read.
How the text is indented is mode dependent.  In programming modes Alpha
will indent blocks of code, like e.g. an if-else statement in C / C++ /
Java / JavaScript etc.

if (a == 5) {
    b = 5;
} else {
    b = 17;
}

How many positions the code is indented is determined by the preference
'Indentation Amount', set in the "Config --> Preferences --> Electrics"
dialog.  By default the code is indented 4 positions for each level of
indentation.

Whether the code will be indented by spaces or tabs is dependent on the tab
size, which can be set in the "Config --> Preferences --> Appearance"
dialog.  By default the tab size is 8.  Thus with the default setting
clearly your code can't be indented using tabs alone.  'Odd' indents will
require a number of tabs plus 4 spaces, and 'Even' indents will be ok with
just tabs.

If you want the code to be indented with spaces only, activate the feature
"Indent Using Spaces Only" in the "Config --> Preferences --> Interface"
dialog .


    ======================================================================


This next section ...

deals with Alpha-specific behavior which may be unfamiliar to new users.


          User interface details


Alpha's interface has several non-standard features, which are described in
this section.


               Horizontal scrollbar


You can remove the horizontal scrollbar from Alpha's windows in order to
give you more real estate.  You can later get the scrollbar back when you
need it.  The menu item Toggle Scrollbar in the Window menu inserts/removes
the horizontal scrollbar.  The default for subsequent windows is controlled
via the preference 'Hor Scroll Bar' ("Config --> Preferences --> Window").


               Dynamic menus


Alpha uses dynamic menus.  This means that some menu items are changed if
you hold down any of the modifier keys.  Usually the option key is the one
which reveals the hidden menu items, but there are also a few items which
are revealed by holding down the control or shift keys.  Try this out by
pulling down the File menu and holding down one of the option, control, or
shift keys.


               Tear-off menus


Alpha's menus can be torn off from the menubar to make floating palettes of
them.  Clicking on the buttons on the palettes performs the same action as
the corresponding menu item.  Note that dynamic menu items are separated
into several buttons, one for each dynamic item.

If the torn off menu has submenus, there will be popup submenus on the
palette.  The submenus can in turn be torn off from the palette (as well as
directly from the menu in the menubar).

If a torn off menu belong to a specific mode, the palette will disappear /
reappear whenever you change from/to that mode.

If you do not want to use tear-off menus, you can disable this feature by
unchecking 'Tearoff Menus' in the "Config --> Preferences --> Appearance"
dialog.

    Bugs:

Buttons in the palettes are not disabled when the corresponding menu items
are.

Torn off submenus belonging to a specific mode are not hidden when you
change from that mode, only the main menu.


               Status bar


The stripe across the bottom of the screen is a floating window which is
used to display short messages.  This window is called the status bar.
Some functions also uses it to prompt for input of some text.

To the right of the status bar there are three menus.

• Wrap menu.  Shows if the lines in the current window are wrapped
automatically and if the wrapping is soft or not.  See the Section Text
Wrapping for more information about text wrapping.

• File Attributes menu.  Shows various attributes of the current window
that can be changed.  What "Mac", "Unix", "IBM", "MPW", "Think", and "None"
means are explained in the Section File formats.

Read only lets you toggle if the current window can be edited or not.  Show
invisibles toggles if invisible characters are shown or not.  This affects
all windows, not only the current one.

Tab size opens a dialog which lets you set the tab size of the current
window, i.e. how many positions a tab uses.

• Mode menu.  Shows the current mode and allows it to be changed.

Finally, to the very right of the status bar the current line and column
are displayed.  Clicking opens a dialog that allows a specific line to be
found.

You can't make the status bar go away.  However, it can be dragged if you
uncheck 'Lock Status' in the dialog "Config --> Preferences --> Window".


               Funcs menu


Above the vertical scrollbar on the right is an icon with curly braces
('{}').  This is the so called "Funcs" menu.  The content of this menu is
mode dependent, but for modes for programming languages it usually lists
function definitions of the the current window.  Select a function in the
menu to jump to its definition in the window.  Refer the mode specific help
files for details about the Funcs menu for a specific mode.  The menu is
built when you press the braces, so it is always up-to-date.

By default, the content in this menu is sorted alphanumerically.  This
feature can be turned off via the preference 'Sort Funcs Menu' in the
dialog "Config --> Preferences --> Appearance", making the menu appear
faster on slower machines.

Power user tip: cmd-opt-K will put up a listpick dialog of the content of
the '{}' menu.  As this is usually alphabetical you can type the starting
letters of the index you want to go to.


               Marks menu


Below the funcs menu is the "Marks" menu, which pops up over the icon with
the large 'M'.  The "Marks" menu lists all marks for the current window,
and allows them to be cleared or automatically created.  Marks are a kind
bookmarks in a file and helps you navigate it.  The marks are saved when
you save the file.  Select an item in this menu to jump to the
corresponding mark in the window.  Selecting 'Mark file' will generate
marks for the current window.  Which marks are generated is mode dependent.
Refer to the mode specific help files for information about which marks are
generated in a specific mode.  For an extended discussion about marks, see
the section 'Marks'.

Tip: ctrl-cmd-K will put up a listpick dialog with the current marks of the
file.


               Icons


Above the Funcs menu is either nothing, a red disk icon, or a lock icon.
The red disk icon indicates that the window is unsaved; clicking on the
icon saves the window.  The lock icon indicates that the window is
read-only; command-clicking toggles the lock icon.  Note, however, that an
unsaved window cannot be made read-only.


               Title bar


Clicking on the window title pulls down a popup menu showing all containing
folders of the window's file.  Selecting an item in this menu puts up a
open dialog in the selected folder.  Selecting an item in the menu while
holding down the shift key opens the folder in the Finder instead of
putting up a file dialog.

Command-clicking on the title bar anywhere but right on the title pulls
downs the Mark menu.  This is also the case you click on the edges of the
window.

Tip: Using the sides of the window lets you access a particular area of the
menu quicker as you can cmd-click in the approximate location of the menu
item you want to select.

Option-clicking on the title bar brings down a menu.  The content of this
menu is mode dependent, but not all modes will define the content of the
menu.  If that is the case, the menu will contain a list of all files and
folders in the open window's folder.  Selecting a file in the menu will
open it.  Selecting a folder will open the containing folder in the Finder.
Note that for windows not saved to the disk there will be no menu with
files.  Even if the mode will create a menu when option-clicking the title
bar, all files and folders in the window's folder may be added to the menu.
This happens if the number of items in the menu created by the mode is less
than what is specified by the preference 'Min Items In Title Popup' which
you find in the dialog "Config --> Preferences --> Window".


               Split-pane bar


Above the vertical scrollbar, right under the Marks menu ('M') is a black
"split-pane" bar.  Double-clicking or dragging the split-pane bar splits
the frontmost window into two separately scrollable panes.  You can also
use the menu item 'Split Window' in the Window menu.  Either pane can be
edited, any changes appear in both panes if they show the same text.  Move
from one pane to the other by clicking in the pane or by typing control-x,
then 'o'.  Go back to a single pane by either double-clicking again or
dragging the bar back to the top of the window.


               Iconified windows


Alpha can create small icons of the windows, which are ordered along the
right edge of your screen.  'Iconify' (ctrl-I) in the window menu creates
an icon of the frontmost window.  If all windows are iconified it expands
one of the windows again.

Checking 'Iconify On Switch' in the "Config --> Preferences --> Window"
dialog will make Alpha do the following:

• Iconify all open windows when you switch to another app.
• Expand all windows, which were not iconified before switching from Alpha,
  when switching back to Alpha.


    ----------------------------------------------------------------------


          Tiling windows


Alpha provides many different ways to move windows around the screen, most
of which are accessible via the windows menu, i.e the menu with the window
icons. The first four items of the "Windows --> Arrange" menu move windows
around a virtual box on the screen, defined by the preferences found in the
dialog "Config --> Preferences --> Tiling".


               Vertically


Tiles 'Num Wins To Tile' number of windows vertically. Preferences which
affects the tiling:
'Tile Top' The position of the upper edge of the top window.
'Def Width' The width of the windows. (Def Width is set in the Windows
preferences dialog.)
'Tile Margin' Controls the gap between the windows.
'Tile Height' Determines the height of the windows by the formula
         (Tile Height + (Tile Margin -1))
height = ________________________________
                Num Wins To Tile


               Horizontally


Tiles 'Num Wins To Tile' number of windows horizontally. Preferences which
affects the tiling:
'Tile Height' The height of the windows.
'Tile Left' The position of the left edge of the left window.
'Hor Margin' Controls the gap between the windows.
'Tile Width' Determines the width of the windows by the formula
         (Tile Width + (Hor Margin -1))
width = ________________________________
                Num Wins To Tile


               Unequal Vert and Unequal Hor


Tile two window by splitting the space between them, with the proportion
assigned to the first controlled by 'Tile Proportion'.


    ----------------------------------------------------------------------


          File formats


Alpha can read and write files stored in different formats.  In the dialog
for the menu item 'Save As…' you can specify in which format a file should
be written through the popup menus State and Format.


               State popup menu


'State' allows you to specify how much extra information should be saved in
files that you use.

MPW     Window position, current selection, tab sizes, and font
        information are saved every time you open and close the file.
Think   Tab sizes, and font information are saved every time you open
        and close the file.
None    No information is saved when you open and close the file.

The state information is saved in the file's resource fork. It is saved
even if you don't modify the file. Saving this information does not change
the modification date of the file.

Note that if a given file already has mpw information in it when the file
is open, Alpha will always update that information when the file is closed.
Note also that marks are always saved in the resource fork whenever a
file is saved, regardless of the 'State'.


               Format popup menu


This menu specifies the way Alpha terminates lines.  This to make it easier
to share files with other platforms as lines are terminated differently on
different platforms.

Mac     Lines end with a carriage return.
Unix    Lines end with linefeed.
IBM     Lines end with both carriage return and linefeed.
            Typical, isn't it?

Alpha will transparently read and write all three of these formats.  If you
are not sharing files with other platforms you don't have to worry about
the format and simply you the default Mac format.  Note that if you are
going to be sharing files with a Unix or IBM machine, you probably don't
want anything in the resource fork, so you'd probably want to set 'State'
to 'None'.

Both the state and format for a file can be change through the File
attributes popup menu in the status bar.

In the dialog "Config --> Preferences --> Window" the default Saved State
can be changed.


    ----------------------------------------------------------------------


               Open file dialog


Alpha's open file dialog looks like the dialog in any other Mac application
except for three extra checkboxes at the bottom.

    Read only ...

Opens the file as read only.  That a file is read-only file is indicated by
a lock icon in the upper right corner of the window.  Read-only status can
be toggled by command-clicking on the icon.  The default action for 'space'
and 'backspace' when a file is read-only is to page forward (closing at the
bottom of the file) or backward.

    Projector Aware Projector ...

is freeware version control software from Apple that is included in MPW. It
also runs as a standalone application known as SourceServer.  It relies on
the existence of a 'ckid' resource in the files.

"Projector aware" means that an application

        must

            not remove this ckid resource if one exists (that means if an
            application saves a file by writing a new one, then delete the
            old and rename the new one it must also make sure to copy over
            an existing ckid-resource even if it uses just the data fork)

        should

            interpret this 'ckid' resource correctly to treat a file as
            read-only if the ckid resource says that the file is read-only
            and not only if the Finder locked flag is set.

However, I don't know how Alpha behaves in these two points.

Finally, a ckid resource can contain a third state between writable and
read-only.  This state is called  MRO (modify read only).
Being a strange term (IMHO) MRO means that a file has been modified locally
but has not been checked out from the version control pool before.

    All files ...

Allows Alpha to open any file rather than just text files.  (Technically
speaking: not only those with file type 'TEXT'.)


               Paragraph format


Word processors such as Microsoft Word and MacWrite only put carriage
returns at the end of paragraphs, so that they can wrap the paragraphs on
the fly.  This is what is referred to as 'paragraph format'.  Alpha does
not transparently convert to and from this format because there are valid
reasons why someone might want to edit a paragraph formatted file while not
in paragraph mode.

Therefore, when Alpha opens a paragraph-mode file, it asks the user whether
or not to remap it.  Alpha assumes a file to be in paragraph mode if it
contains any line longer than the value of 'Para Column', which can be set
in the dialog "Config --> Preferences --> Text".  Files can be mapped back
to paragraph mode by using 'Paragraph to Line' in the text menu.


    ----------------------------------------------------------------------


          Helper Applications


Alpha uses many helper application, e.g. a web browser and an ftp client.
Using by the menu item "Config --> Preferences --> Helper Applications".
you can choose which helpers to use or change.

Now, in some cases a dialog is opened with a popup menu with some popular
apps of the appropriate type.  Either choose one from the popup menu, or
select 'Locate manually' and click OK to locate the app on your disk.

In some cases a file dialog is directly opened to let you locate the helper
app.


          Spell Checking


Alpha has the capability to interact with the spell-checker 'Excalibur',
written by Robert Gottshall and Rick Zaccone.  The menu item 'Spellcheck
Window' is always available in the "Text" menu.  Selecting this item will
start up Excalibur and open the current window in Excalibur.  For version
1.4 and earlier, if Alpha has to launch Excalibur you will need to dismiss
Excalibur's opening dialog by hitting the Cancel button.  Subsequent
selections of the menu item will switch right into Excalibur with the
correct file displayed.

When switching back from Excalibur to Alpha, Alpha reads the corrected
version of the file into the current window.

There is also a menu item 'Spellcheck Selection'.  This copies the current
selection to the clipboard and switches to Excalibur.  You can then use
'Open Clipboard' in Excalibur's File menu to spellcheck the selection.
When you switch back to Alpha you have to paste the corrected text
yourself.

Excalibur can be obtained from

    <http://www.eg.bucknell.edu/~excalibr/excalibur.html>


          Command-clicking


Command-clicking on any text causes Alpha to try find a URL anywhere near
where you click.  If Alpha finds one it sends it to Internet Config which
passes it to the right helper application.  For example, place the mouse
over this text and command-click:

    http://www.alpha.olm.net/

Unfortunately, this feature is rather buggy.  Whenever there is a colon
nearby where you click Alpha usually thinks there is a URL, although there
is not, and sends it to Internet Config.  If Internet Config returns an
error Alpha then interprets your command-click as a command-double-click
instead.


          Command-double-clicking


Command-double-clicking on a word activates a mode specific function which
uses the word you clicked on as input. In several programming modes, Alpha
tries to find the definition of the word you clicked on. Some examples:

When command-double clicking on a word in a C++ file Alpha first checks if
you clicked on an #include statement. Alpha then tries to open the file.
Next Alpha tries to look up the word in the tag file. If the word is not a
tag, or no tags have been specified, Alpha attempts to lookup the word
through the THINK Reference app. If you would like Apple's Toolbox
Assistant to be used instead, edit the proc: C++::DblClick.

In Tcl mode, if you click on a variable Alpha displays its value, if you
click on a command Alpha tries to look it up first in the Tcl folders, then
in "Alpha Commands", and then finally in "Tcl Commands".

          Search and Replace


Alpha has a full repertoire of searching commands.  The 'Find' menu item in
the Search menu brings up a dialog allowing the search and replacement text
to be specified.  Alpha can search either the current open window or a set
of files.

The dialog also allows the following options:

    Forward

To search the text forwards or backwards.  This does not apply when
multiple files are searched.

    Ignore Case

Whether the search should match case or not.

    Word Match

Whether the search should match only complete words or not.

    Batch

When making a batch search, a list of all matches in the fileset or current
window are displayed in a new browser window.  A particular match can be
displayed by moving the cursor to a line in the file of matches and hitting
"return".

    Grep

The search and replace text strings are interpreted as regular expression.
The word 'grep' comes from the unix command with the same name.

    Mult Files

To search through all files in a given file set.  Checking the 'Mult Files'
box brings up a new popup menu.  In this menu you can choose which fileset
to search.  You can either select an existing fileset in the menu or create
a new one by selecting "New Fileset…".  Read more about fileset in the file
"Filesets Help".  In addition to the current filesets, the menu has an item
called 'Directory Scan'.  This allows you to specify a folder that will be
searched.  This folder is also saved at the end of the menu for future
searches.

And finally, Alpha allows a library of useful search and replace texts to
be defined.  This library is used and edited in the popup menu 'Patterns'.
Selecting a pattern from the menu inserts the search and replace strings in
the dialog.  In addition

'Remember Pattern' creates a new item in the menu from the current search
and replace strings.

'Delete Pattern' lets you delete a pattern from the menu.

The global "Filters" menu allows for even more complicated search and
replace functions.  See the "Filters Help" file for more information.


               Incremental Searches


Emacs users will be happy that both forward and backward incremental
searches are implemented.  Incremental searches bypass the normal search
dialog and search for the current text after each keystroke.  The result is
often much faster and less intrusive.  The menu items 'Quick Find' and
'Reverse Quick Find' in the Search menu are the forward and backward
incremental searches respectively.

Start the search either from the menu or by typing ctrl-s or ctrl-r, then
type the word you are searching for.  After each letter you've typed Alpha
jumps to the nearest point in the text matching what you have typed so far.
The search string is also displayed in the status bar.

Typing ctrl-s or ctrl-r again while an incremental search is in progress
causes the search to proceed to the next instance of the current text.
Typing control-w while incremental search is active causes all the
characters to the end of the next word boundary to be added to the search.

Pressing the "Delete" key, or clicking on the window with the mouse will
remove the most recent keystroke from the search pattern, and back up the
search to the most recent find, acting as an internal "Undo" command while
searching incrementally.

To escape or stop a search, press "Return", any of the arrow navigation
keys, or the "Page Up/Down/etc" document navigation keys.


    ----------------------------------------------------------------------


          Browser Window


Browser windows are used to list the result of batch searches, as well as
other similar lists. Each line in the browser window refer to a certain
line in a file, in the case of batch searches the lines where what you
searched for have been found. Navigate the windows using the up and down
arrows, and jump to the match - i.e. the line in the file referred to by
the line in the browser window - by hitting 'return'.

The browser windows are actually in a special mode, the browser mode. The
complete set of keybindings in this mode is:

uparrow             move up one line in the window and select the line
ctrl-p                                      -"-
delete                                      -"-
downarrow           move down one line in the window and select the line
ctrl-n                                      -"-
space                                       -"-
return              go to match
enter                   -"-
ctrl-C ctrl-C           -"-

In the Search menu there is also a very useful command 'Next Match'.
Regardless which window is frontmost, it brings the browser window to the
front, navigate down one line, and goes to the match of that line. Thus,
this gives you a quick way to jump to all matches without having to
manually bring the browser window to the front.



    ======================================================================


This next section deals with ...


"Modes" and "Packages" contained in the AlphaTcl library.


          Modes


Alpha is made for editing text of many different kinds.  Therefore Alpha
can switch between many different modes.  When Alpha switch between the
modes some of Alpha's functionality changes to better help you to write the
particular kind of text you are editing.  For example C++ mode is used to
edit code in the C++ programming language, and HTML mode is used for
editing web pages.  Alpha comes with more than 25 modes, most of them being
modes for different programming languages.  The default mode is called Text
mode and is used for editing plain text, like this manual for example.
Alpha also switches to Text mode when you open a new untitled window.  See
the file "Packages" for a complete list of them and for links for help for
each of them.  This section is only a general discussion about modes.

Simple examples of functionality which changes between the modes are:

• Coloring of the text.  Programming language all have special keywords.
Alpha colors these keywords to make the code easier to read, and these
words are naturally different in different programming languages.

• Alpha indents the code to make it easier to read.  This is also naturally
done differently for different programming languages.

Most modes also add functionality to Alpha, functionality which is not
available for the basic Text mode.  Some modes also have there own menu(s)
which are inserted in the menu bar when switches to the mode in question.
This menu(s) are removed again when Alpha leaves the mode.  Some simple
examples of extra functionality in different modes:

• In C++ mode Alpha can help you to quickly type certain language
constructs, such as for loops.

• In HTML mode there is a function to create a link between two web pages.

It is important to know that Alpha has both global menus and functionality,
which are always there regardless of the mode, and mode specific menus and
functionality, which are only there when Alpha is in a specific mode.  For
instance, the menus from File to Config and the Window menu (the one with
the three windows icon) are global menus.

When you open a file Alpha always chooses a mode for it.  Alpha does its
best to choose the mode you want.  Therefore it is important to know how
Alpha chooses the mode.  The following is considered:

• The suffix in the file name.  For example, 'file.c' is opened in C++ mode
because of the '.c' suffix, 'file.html' is opened in HTML mode because of
the '.html' suffix.  You can view and edit the suffix mapping using the
menu item "Config --> Preferences --> Suffix Mappings…" In this dialog the
suffices for each mode is specified as a list of patterns matching the file
names.  In these patterns * stands for 'any characters', e.g. the pattern
'*.c' matches any file name ending by '.c'.  As an example, for Perl mode
the default patterns are: *.pl *.ph *.pm meaning that any file with a name
ending by '.pl', '.ph', or '.pm' will be opened in Perl mode.

• If the first non-empty line contains a string '-*-Mode: <mode>-*-' or
'-*-<mode>-*-' (without quotes) then Alpha switches to the mode <mode>.
For example, if the first non-empty line contains '-*-HTML-*-' Alpha opens
this file in HTML mode.

• If the first non-empty line reads "#!/dir/subdir/command ..."  then Alpha
tries to find a mode corresponding to 'command'.  This kind of line is used
in unix files.

• In some cases Alpha can choose the mode depending on which application
has created the file.  One example is that files created by MacPerl are
opened in Perl mode.

You can customize which modes Alpha chooses in the last two cases, see the
Sections modeCreator and unixMode.

You can also manually change mode for a window by selecting one in the mode
popup menu in the status bar.  The mode menu is the rightmost of the three
menus in the status bar.  You can also change mode using the menu item
"Config --> Mode Prefs --> Change Mode…"

Once Alpha has chosen a mode for a window, Alpha remembers it when you
switch between the windows, until you manually change the mode for the
window.

Tip: Holding down the shift key while selecting a mode in the mode popup
menu makes Alpha open the help file for the mode instead of changing mode
for the window.  Holding down the option key while selecting a mode in the
mode popup menu makes Alpha give you a description of the mode.  However,
most of this description is hardly of any use unless you know Tcl
programming.


          Alpha's Preferences


Alpha stores most preferences in the "defs.tcl" and "arrdefs.tcl" files in
your preferences folder.  The preferences folder is in the standard system
preferences folder, and is named 'Alpha' (for versions < 7.0) or Alpha-v7
for version 7 (and will be called Alpha-v8 when version 8.0 is released at
some point in the future...)

If you are upgrading to Alpha 7.x from 6.x, some of your old preferences
will be incompatible/irrelevant to the new Alpha version.  Therefore you
shouldn't just copy the two prefs files from one folder to the other.

Here's how to copy over just a few preferences: open the old 'defs.tcl' or
'arrdefs.tcl' and examine them for lines you wish to copy.  Open the new
'defs.tcl' and 'arrdefs.tcl'.  Alpha opens them in read-only mode, but you
can command-click on the 'lock' icon in the window to make the windows
modifiable.  Now copy and paste as you desire.  Finally save the windows
and quit and restart Alpha.  If you get an error on startup, you probably
copied over incompatible preferences and you'll have to delete the files
and start over (hence it may be a good idea to make a backup copy of the
originals before you start).

Note: if you don't wish to use a System-Folder prefs folder, create a
folder called 'AlphaPrefs' next to the Alpha application.  Alpha will use
that folder preferentially if it exists.


               Global and mode preferences


Alpha has two types or preferences, global and mode preferences.

• Global preferences always apply regardless of the mode. These are set in
the various dialogs "Config --> Preferences".

• Mode preferences only apply to windows in that mode, and are set in the
dialog "Config --> Mode Prefs --> Preferences…". Some modes may also have other
means of setting preferences. Note that in some cases there are mode
preferences which coincide with a global preference. In this case the mode
preference override the global one.

The is also another way of customizing Alpha than setting preferences in
these dialogs. That is using preferences files where you add your own Tcl
code. There is both a global preferences file, opened using
"Config --> Preferences --> Edit Prefs File" and a mode specific one opened using
"Config --> Mode Prefs --> Edit Prefs File".

To learn about writing your own code for Alpha, see the section Changing
Alpha's behavior.


               Coloring


Alpha supports automatic coloring of the text. The way Alpha colors the
text depends on the current mode. There are basically three different
things Alpha can color.

Keywords    A set of words with a special meaning, e.g. keywords in
            programming languages.
Strings     Text delimited by double quotes. Alpha can color single-line
            strings only.
Comments    Comments in programming code.

For details about the coloring in a specific mode, see the help file for
the mode. The coloring support in the different modes differ and some
modes have a more complex coloring support than just the basic things
mentioned above.

Colors for keywords, strings, and comments (for applicable modes) can all
be changed via the "Config --> Mode Prefs --> Preferences…" menu item. Some
modes may offer more extensive customization.

By default there are seven different colors to choose between, blue, cyan,
green, magenta, red, white, and yellow. If you wish you can redefine these
via the menu "Config --> Redefine Colors". For instance, you can redefine 'red',
and any text that is currently red will then be the new color you specify.
In addition, there are eight other colors 'Color_9' through 'Color_15'
which you can use to define your own colors. Note that by default these
colors do not show up in the mode preferences dialog because until you have
given them a value they are undefined.

Coloring can be turned off completely by unchecking 'Coloring' in the
dialog "Config --> Preferences --> Appearance".

Additionally, Alpha allows the text color and window background to be
changed. These are changed by redefining 'Foreground' and 'Background' in
the "Config --> Redefine Colors" menu.


               Advanced coloring customization


If you don't find the customization in the mode preferences dialog
sufficient, you can customize the coloring by adding some Tcl code to the
mode preferences file.  This file is opened (or created, if necessary) via
the "Config --> Mode Prefs --> Edit Prefs File" menu item.  Coloring is
defined using the command: regModeKeywords.  See the file "Alpha Commands"
for a complete description on how to use this command.

As an example the line:

    regModeKeywords -a -k blue Fort {blah bladdity}

will add the keywords 'blah' and 'bladdity' colored blue in Fortran mode.


    ----------------------------------------------------------------------


          Packages


Alpha has a very flexible mechanism for adding extra functionality.  Much
of Alpha's functionality has been bundled into a number of so called
packages.  This has two main advantages.  First, the user can choose to
activate only those packages he or she wants and totally ignore the other
ones.  Second, anybody can write and distribute new packages for Alpha.

Alpha comes with a large number of packages.  The remainder of this section
describes some of them, but you can also see the file "Packages" for a
complete list which includes links for package specific help files.

The menu item "Config --> Packages --> Read Help For A Package…" will also
give information about specific packages.  To learn how to install new
packages see the section below on 'Installing New Packages'.

The packages come in three flavors:

• Modes. As have been discussed in the previous section, a mode gives Alpha
some functionality useful for editing text for a particular purpose, for
example writing code in various programming languages.

• Menus. A menu is a package which attaches an extra menu to the menu bar.

• Features. A feature gives you some more functionality without attaching a
menu to the menu bar. However, some features adds a new submenu to a menu
or some new menu items to a menu.

In practice the only difference between 'menus' and 'features' is that
'menus' have their own menus in the menu bar.


Menus and features can be activated and deactivated either globally or for
specific modes.  This is done using the menu items

    "Config --> Preferences --> Menus"
    "Config --> Preferences --> Features"

    "Config --> Mode Prefs --> Menus"
    "Config --> Mode Prefs --> Features"

Some packages are also enabled through "Interface" or "Input-Output"
preferences under the "Config --> Preferences" menu.


          Menus and Features


Activating a menu or feature makes the functionality provided by the menu
or feature available until it is deactivated.  Alpha remembers which ones
are active next time you run Alpha.  Once a menu or feature is deactivated
it does not affect Alpha's behavior at all.  It is then as if it did not
exist.  Note, however, that in some cases you the package is not
deactivated until you restart Alpha.

The page for menus is divided into two sections.

• Usual menus. These are menus designed to be used globally.  These include

  package: alphaDeveloperMenu
  package: codewarriorMenu
  package: colorMenu
  package: cvsMenu
  package: electricMenu
  package: filesetMenu
  package: filtersMenu
  package: frontierMenu
  package: ftpMenu
  package: internetConfigMenu
  package: makeMenu
  package: thinkMenu
  package: thinkRefMenu
  package: toolboxRefMenu
  package: versionControlMenu
  package: voodooMenu
  package: wwwMenu

• Other possible menus. These are menus designed to be used in a specific
  mode or modes.  These include

  package: bibtexMenu            for Bib mode
  package: calcMenu              for Calc mode
  package: camlMenu              for Caml mode
  package: cssMenu               for CSS mode
  package: diffMenu              for Diff mode
  package: eudoraMenu            for Mail mode
  package: gnuplotMenu           for GPLT mode
  package: htmlMenu              for HTML mode
  package: htmlUtilsMenu         for HTML mode
  package: igorMenu              for Igor mode
  package: installMenu           for Inst mode
  package: javaMenu              for Java mode
  package: lispMenu              for Lisp mode
  package: MATLMenu              for MATL mode
  package: mfMenu                for Mf mode
  package: perlMenu              for Perl mode
  package: sasMenu               for SAS mode
  package: scilabMenu            for Scil mode
  package: sMenu                 for S mode
  package: spssMenu              for SPSS mode
  package: stataMenu             for Stta mode
  package: tclMenu               for Tcl mode
  package: texMenu               for TeX mode

Thus, normally it is a good idea to only choose between the menus in the
section 'Usual menus'.  Although it is possible to activate the other menus
globally, they are usually of no use outside the mode or modes they are
designed for.  See the "Packages" file for the current list of menus
available.

The page for features are similarly divided into two sections.

• Usual features. These are features designed to be used globally.
• Other possible features. These are features designed to be used in a
  specific mode or modes.

Also in this case it usually only make sense to choose between the ones in
the section 'Usual features'.  See the "Packages" file for the current list
of features available.


    ----------------------------------------------------------------------


          Electrics - automatic typing by Alpha


The term "electric" is used in the sense of "automatic, power assisted
behavior", which is intended to save time, keystrokes, and brainpower. All
the "electric" features are features, which makes Alpha do automatic typing
for you. The exact behavior is mode dependent.

The items described below can be enabled globally using the menu item
'Config --> Preferences --> Interface Preferences'.  To turn off a global
preference for a specific mode, use 'Config --> Mode Prefs --> Features…'
(See the item "Turn Items Off".)

Many modes specify one or more of these items, which can be reviewed (and
turned off) in the dialog 'Config --> Mode Prefs --> Preferences…'.


               Electric return


Enabling the 'Electric Return' feature tells Alpha to indent the following
line automatically whenever you press return.


               Electric braces


Enabling the 'Electric Braces' feature tells Alpha to treat the left or
right brace '{', '}' keys as special keypresses which enter the '{' or '}'
character, followed by a return and then indent the following line
correctly. It is useful for those programming modes in which '{' and '}'
are used to delineate blocks of code in 'for' loops or 'if-then-else'
groups etc.

If you only want a '{' or '}' without the electric behavior, type option-{
or option-}.


               Electric semicolon


Enabling the 'Electric Semicolon' feature tells Alpha to treat the
semicolon keys ';' as special keypresses which enters the ';' character
followed by a return and then indents the following line correctly. It is
useful for some programming modes in which ';' normally ends a line. The
';' key is context-dependent so you can still enter a for( ; ; ) loop in C
mode (for instance) without Alpha messing things up.
If you want a ';' without the electric behavior, type option-;.


               Electric colon


Enabling the 'Electric Colon' feature tells Alpha to indent lines ending by
a colon differently. This is for those programming modes which uses
switch-case statements like e.g. C/C++, Java, and JavaScript.


               Electric tab


Enabling the 'Electric Tab' feature allows Alpha you to use the functions
'Indent or Next Stop' and 'Complete or Tab' as any of your 'Special Keys'
bindings. By default 'tab' is invokes the function 'Indent or Next Stop',
but there is no key which invokes 'Tab or Complete'.
Indent or Next Stop will first look forward for a template stop '•'. If one
is found Alpha jumps to it and deletes it. If no • is found Alpha will
instead indent the current line.
Complete or Tab will make an electric completion.
If you want to insert a normal 'tab', type option-tab.


               Electric completions


Enabling the 'Elec Completions' feature gives you a set of features to save
you key strokes. When you invoke it Alpha tries to expand what you have just
typed to give the rest of what you want. Electric completion is invoked by
typing control-tab or F1. The documentation will always refer to
control-tab as being the key combination for electric completion.

Electric completions and expansions are enabled globally in the dialog
'Config --> Preferences --> Features…'.  See the "ElecCompletions Help"
file for more information.  Once these features have been turned on, you
could learn more about them by taking the quick "Text Tutorial".

Some modes also have their own tutorial how to use completions in the mode,
opened with "Config --> Mode Prefs --> Completions Tutorial".  See also the
documentation for the mode.  To see a list of all mode-specific completions
tutorials available, see the "Packages" file.

Alpha can complete what you just have typed in several different ways, and
the behavior vary from mode to mode. In many modes Alpha tries a set of
different ways to complete and continues until one of them succeed (or all
fails). Let us start with the simplest kind of completion, but which
normally is tried last when everything else has failed.

Word completion: Type the first few letters of a word and hit control-tab
(or F1). Alpha will then search the document for a word which begins with
these letters. If one is found Alpha completes the word you have just typed
the first letters of. If this is not the word you want, hit control-tab
again and Alpha continues searching for another one beginning with the same
letters. Hitting control-tab repeatedly will cycle through all words in the
document beginning with these letters until no more such word is found.
Alpha always starts searching backwards from the point where you are until
is reaches the top of the document, then is continues searching forwards
from the point where you are until the end of the document.

An example: Typing 'com' right here and hitting control-tab will expand
this to 'completes', which is the first word beginning by 'com' found above.
Hitting control-tab again without moving the insertion point will expand it
it 'completes', which is the next word beginning by 'com' found above.

Command template completion: For for loops, if statements and similar
constructs used in programming languages Alpha can insert a template. As
an example let's make an 'if' template for C, C++, Java, and other
languages using the same construct. Simply type

    if

(when Alpha is in C, C++, or Java etc. mode!) and hit control-tab. Alpha
then inserts a template

    if (|){
        •
    } •

with the insertion point between the parentheses. The bullets '•', which
are inserted are called template stops. When you hit tab, Alpha jumps to
the next template stop and deletes. To use the template first type the
condition and then hit tab. Alpha the jumps to the first bullet and deletes
it. Then type the body of the if statement and finally hit tab again to
jump to the last template stop. Note! The feature 'Electric tab' must be
enabled for the mode in question to be able to jump between the template
stops with tab, see below.

This section has only been a short introduction to electric completions.
More detailed help is found in "ElecCompletions Help".


               Electric expansions


Enabling the 'Elec Expansions' feature provides you with a special kind of
word completion. When you find yourself typing a lot of variable and
function names over and over, and these names are word-combinations where
the name is formed by either capitalizing each word or separating them with
an underscore, just type the initial letter of each word and invoke
electric expansion instead. This is often shorter and more natural than
typing a few letter and using electric completions to make a word
completion. Electric expansion is invoked by typing command-space.

The string you are going to use expansion on is entered in lowercase. The
words in the target you are trying to hit have to start with a capital
(except the first word), or, be separated by an underscore.

The hint can be embedded between non-alphabetic characters and certain
punctuation marks ( '[', '(', '{', ',', ';', ':', ''', '"', ']', ')', '}'
). The expanded hint remains so embedded, and the cursor appears one space
beyond the trailing punctuation.

An example: Let's say there is a word 'someLongWord' in the file. Then
typing 'slw' and hitting command-space will expand 'slw' to 'someLongWord'.

Another example: Let's say there is a word 'some_long_word' in the file. Then
typing 'slw' and hitting command-space will expand 'slw' to 'some_long_word'.

This section has only been a short introduction to electric expansions.
More detailed help is found in "ElecCompletions Help". Some modes may also
their own special expansions features, see the help files for the respective
modes.


               Special keys dialog


The dialog "Config --> Special Keys…" is used to define the keys which
activate the electric completion and expansion functions and which let
you jump between the template stops. You can define keys for the following
functions:

Function                Action
--------                ------
Expand                  Electric expansion.
Next stop or indent     Alpha first looks forward for a template stop '•'.
                        If one is found Alpha jumps to it and deletes it.
                        If no • is found Alpha will instead indent the
                        current line. This requires that 'electric tab' is
                        enabled, otherwise a tab is inserted.
nth Stop                Jumps to the nth template stop.
Complete or Tab         If 'electric tab' is enabled Alpha will make an
                        electric completion, otherwise a tab is inserted.
Next stop               Jump to the next template stop '•' and delete it.
Clear all stops         Delete all template stops '•' in the window.
Complete                Electric completion.
Real tab                Inserts a tab.
Prev stop               Jump to the closest template stop '•' before the
                        current position and delete it.

There are two predefined sets of key bindings for these functions. The
alternative set is define to use key bindings like those which are used in
Emacs. In the dialog "Config --> Special Keys…" you can choose one of these
two sets of bindings or define your own.

Function                Default binding             Alternative binding
--------                ---------------             -------------------
Expand                  command-space               command-space
Next stop or indent     tab                         no binding
nth Stop                no binding                  control-tab
Complete or Tab         no binding                  tab
Next stop               no binding                  control-j
Clear all stops         shift-control-tab           shift-control-tab
Complete                control-tab                 no binding
Real tab                option-tab                  option-tab
Prev stop               shift-tab                   shift-control-j


    ----------------------------------------------------------------------


          Regular Expressions


Many packages use 'Regular Expressions' in their procedures.  Here's a
summary of how regular expressions work in Alpha (but see also the help
file "Regular Expressions".)

Regular expressions are used to find the part of a string which matches a
certain pattern.

A regular expression is zero or more branches, separated by `|'. It matches
anything that matches one of the branches.

A branch is zero or more pieces, concatenated. It matches a match for the
first, followed by a match for the second, etc.

A piece is an atom possibly followed by `*', `+', or `?'. An atom followed
by `*' matches a sequence of 0 or more matches of the atom. An atom
followed by `+' matches a sequence of 1 or more matches of the atom. An
atom followed by `?' matches a match of the atom, or the null string.

An atom is a regular expression in parentheses (matching a match for the
regular expression), a range (see below), `.' (matching any single
character), `^' (matching the null string at the beginning of the input
string), `$' (matching the null string at the end of the input string), a
`\' followed by a single character (matching that character), or a single
character with no other significance (matching that character).

A range is a sequence of characters enclosed in `[]'. It normally matches
any single character from the sequence. If the sequence begins with `^', it
matches any single character not from the rest of the sequence. If two
characters in the sequence are separated by `-', this is shorthand for the
full list of ASCII characters between them (e.g. `[0-9]' matches any
decimal digit). To include a literal `]' in the sequence, make it the first
character (following a possible `^'). To include a literal `-', make it the
first or last character.

If a regular expression could match two different parts of the input
string, it will match the one which begins earliest. If both begin in the
same place but match different lengths, or match the same length in
different ways, life gets messier, as follows.

In general, the possibilities in a list of branches are considered in
left-to-right order, the possibilities for `*', `+', and `?' are considered
longest-first, nested constructs are considered from the outermost in, and
concatenated constructs are considered leftmost-first. The match that will
be chosen is the one that uses the earliest possibility in the first choice
that has to be made. If there is more than one choice, the next will be
made in the same manner (earliest possibility) subject to the decision on
the first choice. And so forth.

For example, `(ab|a)b*c' could match `abc' in one of two ways. The first
choice is between `ab' and `a'; since `ab' is earlier, and does lead to a
successful overall match, it is chosen. Since the `b' is already spoken
for, the `b*' must match its last possibility-the empty string-since it
must respect the earlier choice.

In the particular case where no `|'s are present and there is only one `*',
`+', or `?', the net effect is that the longest possible match will be
chosen. So `ab*', presented with `xabbbby', will match `abbbb'. Note that
if `ab*' is tried against `xabyabbbz', it will match `ab' just after `x',
due to the begins-earliest rule. (In effect, the decision on where to start
the match is the first choice to be made, hence subsequent choices must
respect it even if this leads them to less-preferred alternatives.)

To summarize, regular expressions are built up of the following pieces:

 c        literal char.
 ^        beginning of line.
 $        end of line.
 .        any character except carriage return.
 [...]    character class, can use ranges such as '0-9'.
          inside classes. Matches one character of the
          enclosed choices. Ex: '[ac0-2]' matches 'a',
          'c', '0', '1', or '2'.
 [^...]   negated character class, matches anything but
          the enclosed characters. ']' can be included
          by putting it immediately after the '^'.
 \t       tab.
 \r       carriage return or line break.
 *        zero or more occurrences of the previous
          pattern. Ex: 'ab*' matches 'a', 'ab', 'abb',
          'abbb' etc.
 +        one or more occurrences of the previous
          pattern.
 ?        zero or one occurrences of the previous
          pattern. Ex: 'ab?' matches 'a' or 'ab'.
 a|b      matches either a or b. If enclosed in
          parenthesis, the extent of the alternated
          expressions is limited. Ex: (pete|bob)
          matches either 'pete' or 'bob'.
 (...)    The interior elements are grouped together.

Regular expressions constructed from the above elements can be
concatenated to create larger expressions.

The parenthesis also define substrings of the total matched string that
can be used either later during substitution. The substring delimited by
the pair of parenthesis that includes the nth left paren is denoted \n,
where n is 1, 2, .... 9.  '\0' and '&' both refer to the matched text.

[examples to be added]


    ----------------------------------------------------------------------


          File Patterns


Some functions require that you give a file pattern which specifies a set
of file names, e.g. if you want to change the suffix mappings you must give
a pattern specifying which files should be opened in a certain mode, and as
another example if you want to create a fileset you must give a pattern
specifying which files should belong in the fileset.

A file pattern is given as a string including special characters, which
allow automatic substitution of characters in file names.

    ?           Matches any single character.

    *           Matches any sequence of zero or more characters.

    [chars]     Matches any single character in chars. If chars contains a
                sequence of the form a-b then any character between a and b
                (inclusive) will match. To match '-' give it as the first
                character between the brackets.

    \x          Matches the character x. This is useful if you want to
                match any of the special characters, e.g to matching '*' is
                done by the pattern '\*'.

    {a,b,...}   Matches any of the strings a, b, etc.

Some examples of how to use file patterns:

• To match any file ending by '.c' use the pattern '*.c'. This will match
files with names like 'blah.c' 'bladdity.c' 'gghjcdhj.c'.

• To match any file ending by '.c' or '.h' use the pattern '*.{c,h}'. This
will match files with names like 'blah.c' 'blah.h' 'bladdity.c'
'bladdity.h'.

• Lets say you have files with names 'chapter1.tex', 'chapter2.tex' through
'chapter50.tex'. To match the first 9 chapters you could use the pattern
'chapter?.tex' This will match the files 'chapter1.tex' through
'chapter9.tex'. Another pattern which would match the same files is
'chapter[1-9].tex'.

• To match the files 'chapter1.tex' through 'chapter9.tex' and
simultaneously files 'chapter1.log' through 'chapter9.log' you can use the
pattern 'chapter[1-9].{tex,log}'


          Marks


Alpha allows the user to use "marks" to remember positions in files. Marks
"float". That is, if a mark is initially at position 312 and then five
characters are inserted at location 297, the mark's new value will be 317.
Alpha uses three different types of marks.

The first is generically referred to as "the mark". The mark is set to the
current insertion point by the command 'Set Mark' (control-space). (This
requires that the Emacs feature is active.) The position in the file
indicated by the blinking cursor is referred to as the current insertion
point. Many commands (such as "cut" and "copy") can operate either on the
currently selected (hilighted) text, or the text between the current
insertion point and "the mark".

For example, if you move the cursor to the beginning of the word
"allybaba", hit control-space (the status bar should say "Mark set"), move
to the end of the word and hit option-W (the status bar should say "Region
copied"), the effect is the same as if you had used the mouse to select the
text and then selected the "Copy" command from the "Edit" menu.

The second type of mark are the permanent marks. Permanent marks are set,
removed, and moved-to through the three corresponding menu items in the
"Search --> Named Marks" menu. Permanent marks differ from the generic mark in
that they have names, there can be any number of them, and they are saved
in the resource fork if the file is subsequently saved.

Permanent marks can be accessed via the "Search --> Named Marks" menu items,
by a popup menu called by mousing down on the M icon above a vertical
scrollbar, or by command-mousing on a window's titlebar.


          File Comparison


With Alpha you can compare files and display the differences in them.
Among other things, this allows you to easily pinpoint what has changed
between two different versions of the same file.  The "Utils --> Compare"
menu items allow you to either compare the two topmost windows, or two
arbitrary files or two entire folders.  In the case of two folders each
pair of files with identical names in the two folders are compared.  It is
also indicated which files are only found in one of the folders.

The comparison is done using a port of the unix GNU diff program.

Alpha opens the two files in windows at the top of the screen with the diff
file at the bottom. You can navigate between individual differences in the
diff file by using the Up and Down arrows. The section of the files which
differ are then selected in the two files.

This section has only been a short introduction to the use of file
comparison with Alpha. Read more in the file "Diff Help"

Bugs: File comparison only works if the files have Mac line terminations.


          Backups


Alpha can automatically make a backup copy for you of the old version of a
file whenever you save changes.  This is done if you check 'Backup' in the
preferences dialog "Config --> Preferences --> Backups".  By default the
backup file is saved in the same folder, and its name is formed by
suffixing a tilde to the name of the saved file.  The backup behavior can
be modified by changing the following preferences found in the dialog
"Config --> Preferences --> Backups":

    Backup

Check this if you want Alpha to make backups.

    Backup Folder

The folder where to save the backups.  If none specified the backups are
saved in the same folder as the original.

    Backup Extension

The extension to add to name of the backup file.  Don't pick a long
extension!  The total file name mustn't be more than 31 characters.

    Backup Age Requirement In Hours

A new backup file is only created if the old backup file is older than
this.


If you have chosen a backup folder and want to go back to the default
behavior of saving the backup in the document's folder this is how to do
it:

Delete or rename the backup folder. Alpha will then ask you if you want to
create the backup folder. If you answer 'No' Alpha will revert to the
default behavior.


               Auto saving


Alpha can automatically save the documents for you after a certain number
of changes.  This is done if you check 'Auto Save' in the preferences
dialog "Config --> Preferences --> Backups".  Alpha then saves the
documents every 'Changes Lim' changes.  'Changes Lim' can be set in the
same preferences dialog.  Note that Untitled windows are not autosaved.


          Tags


Alpha supports the use of tags to find declarations of functions; by
default this is set up only for 'C'. When searching for a tag, Alpha looks
for the tag file specified by the 'Tag File' preference, which can be set
in the dialog "Config --> Preferences --> Tags". Alpha's tag generating routines
use the regular expression in the preference 'Func Expr' to look for
function declarations. In other words, we don't parse the text. If you
declare your functions differently, you can change 'Func Expr' to suit your
own style. Alpha currently uses the following regular expression to find C
function declarations:

    ^[^ \t\(#\r/@].*\(.*\)$

Although complicated, this expression makes sense if you slowly wade
through it.  The string that we are looking for must take up an entire
line.  It must begin with a character other than '\t', '#', '\r', '/', ' ',
'(', or '@'.  There must be a set of parenthesis.

Note that not only can you customize this to your style of 'C'
declarations, you could also use it to generate tags for other languages.
The only thing you need to bear in mind is that the tag routines use the
complete word previous to the first '(' in the selected line as the
function's name.  If there is no '(' in the selected line, the last word in
the line is used.  Therefore, Pascal procedures with or without parameters
can be identified.

Caveat: Apple's list manager can't handle more than 32k of text in the
entire list, so there is a practical limit of 2000 or so tags in your
project.


          Calculator


Alpha has its own calculator. This is just a quick-and-dirty RPN stack
calculator, which works on both signed and unsigned decimals, hex integers,
and floating point.  See the "Calculator Help" file for more information.



    ======================================================================


This last major section of the Alpha Manual ...

concerns upgrading or otherwise enhancing Alpha, either by installing new
packages written by various Alpha users and developers, or by writing your
own packages.


          Installing New Packages


               Where to find new packages


Currently the best place to look for new packages is

    <ftp://ftp.ucsd.edu/pub/alpha/>.

For those from Europe, you may wish to try the mirror:

    <ftp://anu.theologie.uni-halle.de/comp/mac/Alpha>


               What is already installed?


It is obviously a waste of time to install something which is already
installed or - worse - to install an old package replacing a more recent
version.  The "Packages" help file lists all packages which are installed.
The list contains the package names, versions, and maintainers.  This file
can be updated at any time with the "Config --> List Packages" menu item.

If there is no version number listed in the "Packages" file for the package
you are about to install, you can find the version number in the beginning
of the tcl file.  Look for a line of one of the forms:

    alpha::extension <name> <version> ...
    alpha::menu <name> <version> ...
    alpha::mode <name> <version> ...

Make a sure the number given by <version> is higher than the one for the
currently installed package.


               Installing


How to start the installation depends on if the package you are about to
install is accompanied by a file 'READ ME TO INSTALL' (or similar) or is
just a single file someName.tcl.

• If there is a file 'READ ME TO INSTALL', open it (hence the name!).  All
packages built up of more than one file must actually have such a read me
file in order to be possible to install.  If there is a file
installScript.tcl (or similar), don't open it.  It only contains
instructions to Alpha what to install.

• If there is only a single file someName.tcl, open it.  Some single file
package are configured to automatically close themselves and open a
installation dialog.  Otherwise proceed as below.

If there are instructions in the read me file how to install the package,
follow them (of course!).  In other cases this is how a typical
installation is made.

• After you have open the read me file or the single someName.tcl, make
sure Alpha has inserted a menu 'Install' in the menu bar.  This means Alpha
is in installation mode.  If not, you can manually switch to installation
mode by selecting 'Inst' in the mode popup menu in the statusbar.

• Select 'Install --> Install This Package' from the Install menu.

• An installation dialog is now opened.  Here you can choose to make an
Easy Install or a Custom Install.  The Custom Install lets you choose
exactly what to install.  The Easy Install installs everything.  If you are
not sure which files you need use the Easy Install.

• There are also three options in the installation dialog.

If 'Backup removed files' is checked Alpha will save any removed file in a
folder InstallationBackup in Alpha's folder.  This as a safety measure so
you can recover any changes you may have made to them or so you can switch
back to them if the newly installed package doesn't work as you wish.

If 'Show installation log' is checked a window is opened after installation
showing which files have been put where and which files have been deleted.

If 'Force overwrite, even of newer files' is checked then newer existing
files will be replaced by those you are about to install.

After Alpha has put the files in there correct location Alpha rebuilds its
index files.  This make take a little while.  The index files are used by
Alpha to keep track of where the various packages and function are.

After the installation is completed you must quit and restart Alpha.


               If something goes wrong


What to do if you're unlucky and have installed a package which simply
doesn't work, possibly crashing Alpha when it's launched?  The obvious
thing is then to uninstall the package.  If Alpha can be launched with the
new package installed you can uninstalling it using the method in the next
section.

If the newly installed package causes Alpha to crash when you launch it,
the situation is more problematic.  Then you have to manually delete some
files to make Alpha run again.  First delete the files you've just
installed.  During the installation the package's files are copied to
various locations in the folder "Tcl" inside Alpha's folder.  Locate and
delete the ones with the same names as the ones in the set of files you
installed.  Then before you launch Alpha again you have to delete a folder
from Alpha's preferences folder.  Alpha's preferences folder is called
"Alpha-v7" and is located in the Preferences folder in the system folder.
Delete the folder "Cache" inside "Alpha-v7".  Deleting the folder "Cache"
is harmless.  It will be re-created the next time you launch Alpha.  It is
very likely, though, that the old content was causing Alpha to crash.

If this doesn't help, as a last way out try removing the complete
"Alpha-v7" from the Preferences folder.


          Uninstalling Packages


Many packages support a mechanism for uninstalling them.  Please note
before starting to uninstall packages you think you won't ever need that
the only thing you save by uninstalling a package is disk space - unless
you have installed some buggy package causing obvious problems.  Installed
packages which are not in use, i.e. either not enabled through the dialogs
'Config --> Preferences --> Menus' / 'Config --> Preferences --> Features',
or modes which are not used, are never loaded into Alpha's memory.  Thus
you do not save any memory by uninstalling packages.  Thus if you have
plenty of disk space, there is hardly any point in uninstalling anything.

The menu item "Config --> Packages --> Uninstall Some Packages" uninstalls
packages.  Select the package you want to uninstall from the popup menu in
the dialog.  All files belonging to the package are now permanently
deleted.  Only a reinstallation will restore the package.

After the uninstallation you must restart Alpha.

If you can't find the package you want to uninstall in the popup menu, it
means that the package doesn't support the mechanism for automatic
uninstallation.  In this case the only way uninstall the package is to
manually find the files belonging to the package and delete them.  Don't
use this method unless you know what you are doing.  Deleting the wrong
files may result in all sorts of troubles.


          User Defined Key Bindings


Alpha allows you to customize the keystrokes you use to invoke editor
functions.  Any Tcl command can be bound to any single keystroke.  Key
bindings can be stored in a global "prefs.tcl" file, or if they are mode
specific, in a <mode>Prefs.tcl file.  The first item is available under the
menu item "Config --> Preferences --> Edit Prefs File".  This file will be
sourced upon every restart of Alpha.


Please see the help file "Default Key Bindings" for more information.


          Changing Alpha's behavior


The rest of the manual discusses some general topics about how to extend
Alpha by writing your own Tcl code.

First of all, where do you put your own Tcl code so that Alpha can find it?
Alpha has a set of preferences files for this purpose.  There is one global
preferences file which is loaded when Alpha is launched.  In this file you
should put code which should be loaded regardless of which mode you're
working in.  This preferences file is opened / created using the menu item
"Config --> Preferences --> Edit Prefs File".

Then there is one preferences file for each mode.  The file for a mode is
loaded after as the last code to be loaded when a mode is used the first
time.  This preferences file can be opened /created using the menu item
"Config --> Mode Prefs --> Edit Prefs File".

These preferences files are intended for code for personal use. If you want
to write a complete new package for Alpha, which others also can use, read
the file "Extending Alpha".


          ALPHA-D mailing list


There is mailing list for Alpha where you can discuss problems, suggest new
features etc. To subscribe, email <[e-mail]> and, in the
body of your message (not the subject line), write:

    SUBSCRIBE ALPHA-D

There are a number of known bugs which will hopefully be corrected in a
future release.  PLEASE read the "Bug Reports and Debugging" file for a
list of known bugs, and for how to give an informative bug report, without
which it is unlikely any bug you found can be fixed.


    ----------------------------------------------------------------------


          Menus, user-defined


If you want to make your own menu with your personal Tcl functions, this
section explains how to do it.  If you want to add new menu items to the
existing menus, see the next section for instructions.  However, in that
case you also need to read this section.

Alpha's menu commands allow the user to build custom menus which contain
names of functions, macros, or arbitrary TCL commands that just HAVE to be
in the menus, as opposed to being merely callable through the bindings.
The menu items are defined as a list of strings.  The following meta
characters can be embedded in the strings:

    Meta-character     Usage
    --------------     -----

    ; or Return       Separates multiple items.
    ^                 Followed by an icon number, adds
                      that icon to the item.
    !                 Followed by a character, marks the
                      item with that character.
    <                 Followed by B, I, U, O, E, or S,
                      sets the character style of the item.
    /                 Followed by a character, sets up
                      a keyboard equivalent.
    (                 Disables the item. Use (- to get a
                      separator line.

The following modifiers can be used to require other combinations of
modifiers than just the command key.  Control-option, for instance, is
specified by putting the string "<B<I" in the menu item.  The menu symbol
for shift is an upward outline arrow, control is the outlined ^ symbol
("Wins --> Iconify" has one), and option is the wavy line with the dot in
the upper right ("Search --> Replace All" has one).  The following are
characters that can follow the '<' and what they signify.

    B       - control key required
    I       - option key required
    U       - shift key required (only for alpha-numerics!)
    O       - command key required
    S       - is part of a dynamic item.
    E       - forces item to start new dynamic item.


A '/' followed by a character in the left column sets up a keyboard
equivalent for the key in the right column:

    a   Enter           n   F10
    b   Return          o   F11
    c   Tab             p   F12
    d   Num Lock        q   F13
    e   F1              r   F14
    f   F2              s   F15
    g   F3              t   Help
    h   F4              u   Del
    i   F5              v   Forward Del
    j   F6              w   Home
    k   F7              x   End
    l   F8              y   Page Up
    m   F9              z   Page Down

The menu creation syntax is :

    Menu [-s] <-n name> <-i num> [-p procName] [-m] [-M <mode>] "Tcl list of menu items"

Where the arguments have the followings meanings:

  -s            Use system menu definition proc (faster).
  -i <num>      Resource id of icon suite to use for menu title.
  -n <name>     Name of menu.
  -m            No menu form. If not supplied, each menu item is split into
                words at each capitalized letter.
  -p <pname>    Rather that having alpha call a Tcl proc named by the menu
                item's text, this option tells Alpha to call the tcl proc
                named by 'pname' with two arguments: the menu name, and the
                text of the menu item chosen.
  -M <mode>     Bindings only take effect in specified mode.

The 'Tcl list of menu items' can include another menu definition allowing
you to create hierarchical menus.  Once the menus are created, they can be
inserted and deleted from the menu bar by the syntax:

    insertMenu "name"
    removeMenu "name"

As alluded to above, Alpha attempts to make procedure names readable in the
menus by separating words at any capitalized letter.  For example,
'findFile' becomes "Find File".  This function is turned off by the '-m'
option.

Menu items can be enabled and disabled through the TCL command
'enableMenuItem'.  Menu items checkmarks can be turned on and off via
'markMenuItem'.  Menu items can be appended via 'addMenuItem' and deleted
via 'deleteMenuItem'.  See the "Alpha Commands" help file for syntax.

As explained above, Alpha uses various keys to specify text style and key
equivalents.  Sometimes you may want these characters included in your text
literally.  If an ampersand ('&') is the last character in a menu item,
these special characters are not interpreted.

If an ellipsis ('…') is the last character in a menu item (except possible
for the above ampersand), it is stripped off before searching for the
function corresponding to the chosen item.


          Modifying Alpha's menus


Alpha's global menus and most mode menus can be modified using commands
menu::insert, menu::removeFrom, and menu::replaceWith.  The use of these
are explained in the section Adding items to global menus in the file
"Extending Alpha".


          Event hooks


When certain events occur.  e.g. when opening and closing windows, Alpha
calls an event hook.  You can register your own event hooks to add to the
default behavior when the corresponding event occurs.  Below is a table of
all available hooks.

To add your own hook there are two things you have to do.  First write a
proc to be called when some events occurs.  This proc must have the
parameters shown in the table.  Lets say you want to define a saveHook.
Then define some proc

    proc mysaveHook {name}{
        .
        .
    }

The next thing you have to do is to register the proc.  This is done with a
line like:

    hook::register 'hook-name' 'your proc' 'mode' ?... 'mode'?

The optional mode parameters specify in which modes the hook will be
called.  If no mode parameters are given the hook will be called regardless
of the mode.  Avoid this unless absolutely necessary.

Let's assume that you want your hook to be called in TeX and Perl modes.
To register it you would use the line:

    hook::register saveHook mysaveHook TeX Perl

Note, however, that a few hooks doesn't use the mode to determine when to
be called and should be registered slightly differently, see below.


               Window hooks

    Hook                                              Parameter(s)

• activateHook                                      path to file
  Called when a window is brought to front
• deactivateHook                                    path to file
  Called when a window is sent to back
• openHook                                          path to file
  Called when a window is opened
• closeHook                                         path to file
  Called when a window is closed
• saveHook                                          path to file
  Called when a window is saved
• saveasHook                                        path to old file, path to new file
  Called when a window is saved as
• savePostHook                                      path to file
  Called after a window is saved

               Alpha hooks

    Hook                                              Parameter(s)

• startupHook
  Called at the end of startup
• quitHook
  Called when quitting Alpha
• suspendHook                                       an empty string
  Called when switching to another app
• resumeHook                                        an empty string
  Called when switching to Alpha from another app

               Mode hooks

    Hook                                              Parameter(s)

• mode::init
  Called the first time a mode is loaded
• changeMode                                        new mode
  Called when the mode is changed
• dialog::modifyModeFlags                           a string (title of dialog)
  Called after a mode prefs dialog is closed
• mode::editPrefsFile
  Called when a mode prefs file is opened
  for editing

               Keyboard hooks

    Hook                                              Parameter(s)

• keyboard
  Called at startup and when the keyboard prefs
  is changed
• removekeyboard
  Called when the keyboard prefs is changed

The keyboard hooks use the keyboard name (the ones in the keyboard popup
menu in the International preferences dialog) rather than the mode to
determine when to be called.  Thus to register a keyboard or removekeyboard
hook use lines like:

    hook::register 'hook-name' 'your proc' 'keyboard name' ?... 'keyboard name'?

               Miscellaneous hooks

    Hook

• launch
  Called when a helper app is launched by calling app::ensureRunning

The launch hook uses the application signature rather than the mode to
determine when to be called.  Thus to register a launch hook use a line
like:

    hook::register launch 'your proc' 'signature' ?... 'signature'?

• requireOpenWindowsHook
  Called when opening and closing windows.

This hook is used to en-/disable meaningless menu items which would require
the presence of a certain number of windows to be active.  You can register
your own menu items using a line like:

    hook::register requireOpenWindowsHook [list menu item] N

where 'N' is the number of windows required (1 or 2 usually)

As an example, this is a line from Diff mode registering the item 'Compare
Windows' to require 2 open windows to be enabled.

    hook::register requireOpenWindowsHook [list compare windows] 2


    ----------------------------------------------------------------------


          modeCreator

The modeCreator array allow you to tell Alpha which mode to choose when you
open a window depending on which application has created the file.  Add to
this array with lines like:

    set modeCreator(<signature>) <mode>

'Signature' is the signature of the application which has created the file
and 'mode' is the mode which you want Alpha set for the window.  For
example, to open all files created by Netscape in HTML mode use the line:

    set modeCreator(MOSS) HTML

Tip: To find the signature of an application, launch it, open the Tcl shell
(command-Y,) and type 'ps' at the prompt.  This will list all running
applications; the second column lists the signatures.

(Or click here --> <<shell; insertText "ps" ; Shel::carriageReturn>>)


          unixMode


When you open unix files where the first non-empty line reads
'#!/dir/subdir/command ...'  then Alpha tries to find a mode corresponding
to 'command'.  With the unixMode array you can tell Alpha which mode to
choose when opening such a file.  Add to this array with lines like:

    set unixMode(<command>) <mode>

where 'command' is the command in the line '#!/dir/subdir/command ...'  and
'mode' is the mode which you want Alpha set for the window.  For example,
to make Alpha open files with a line '#!/dir/subdir/perl ...'  in Perl mode
use the line:

    set unixMode(perl) Perl


          Word breaking


Alpha allows you to redefine its internal notion of what a word is, through
the preferences 'Word Break', and 'Word Break Preface'.  'Word Break' is
set to a regular expression that defines a word to you.  'Word Break
Preface' should be a regular expression that matches exactly one of any
characters that are not in your word definition.

The value of 'Word Break' and 'Word Break Preface' are mode dependent, as
what is meant by a word may be different for different types of text.  For
example, in Text mode the default definition of 'Word Break' is '\w+'.
This matches any contiguous sequence of contiguous alphanumeric characters.

The default value in Text mode for 'Word Break Preface' is '(\W)',
basically just the negation of any any of the characters in your 'Word
Break' definition.

The need for both these variables in backward searches can be seen as
follows.  Suppose your window's text is 'hey hello', and the current
insertion is between the two 'l's.  Now, searching backwards for the above
'Word Break' definition will take the insertion to between the 'e' and the
first 'l', not really where we want to say is the start of the word.  By
contrast, if we search backwards for 'Word Break Preface' and 'Word Break'
concatenated together, and then move forward one character after a
successful search, we end up right before the 'h' in 'hello', just where we
want to be.

There are also two similar preferences 'Wrap Break' and 'Wrap Break
Preface' used for automatic word wrapping.  In Text mode their default
values are '[\w_]+' and '([^\w_])' meaning that wrapping should not occur
between alphanumeric characters or underscore.


    ======================================================================


Author: Peter Keleher

Contributors: This manual has been updated / revised by many helpful users
and developers over the years, as noted above.

    ----------------------------------------------------------------------

This file was last updated by Craig Barton Upright, Donavan Hall.

E-mail: <[e-mail]>
  mail: Princeton University,  Department of Sociology
        Princeton, New Jersey  08544
   www: <http://www.princeton.edu/~cupright/>

E-mail: <[e-mail]>